<!DOCTYPE html>
<html lang="en" >
<head>
    <title>Atomsk - Option disloc - Pierre Hirel</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <link rel="stylesheet" media="screen" type="text/css" title="Default" href="./default.css" />
    <link rel="icon" href="../img/atomsk_logo.png" type="image/png" />
</head>
   
<body>

<p><a href="./index.html">Back to main menu</a></p>

<h2>Option: dislocation</h2>

<h4>Syntax</h4>

<p><code>-dislocation &#60;p<sub>1</sub>&#62; &#60;p<sub>2</sub>&#62; screw &#60;&xi;&#62; &#60;n&#62; &#60;b&#62;</code></p>

<p><code>-dislocation &#60;p<sub>1</sub>&#62; &#60;p<sub>2</sub>&#62; &#60;edge|edge_add|edge_rm&#62; &#60;&xi;&#62; &#60;n&#62; &#60;b&#62; &#60;&nu;&#62;</code></p>

<p><code>-dislocation &#60;p<sub>1</sub>&#62; &#60;p<sub>2</sub>&#62; mixed &#60;&xi;&#62; &#60;n&#62; &#60;b<sub>1</sub>&#62; &#60;b<sub>2</sub>&#62; &#60;b<sub>3</sub>&#62;</code></p>

<p><code>-dislocation loop &#60;x&#62; &#60;y&#62; &#60;z&#62; &#60;n&#62; &#60;radius&#62; &#60;b<sub>x</sub>&#62; &#60;b<sub>y</sub>&#62; &#60;b<sub>z</sub>&#62; &#60;&nu;&#62;</code></p>


<h4>Description</h4>

<p>This option allows to insert a straight dislocation line or a dislocation loop into the system, using the displacements predicted by the theory of dislocations. Either isotropic or anisotropic solutions can be used (see below). The equations used by this option can be found e.g. in J.P. Hirth and J. Lothe, <em>Theory of dislocations</em>.</p>

<p>The user must provide the following parameters (see <strong>Fig. 1</strong>):</p>

<ul>
  <li><strong>p<sub>1</sub>, p<sub>2</sub></strong>: coordinates of the dislocation in the plane normal to the dislocation line (see &xi; below), by order of permutation X, Y, Z: if &xi;=Z then p<sub>1</sub> is the position along X, and p<sub>2</sub> the position along Y; if &xi;=Y then p<sub>1</sub> is along Z and p<sub>2</sub> along X; if &xi;=X then p<sub>1</sub> is along Y and p<sub>2</sub> along Z. The positions &#60;p<sub>1</sub>&#62; and &#60;p<sub>2</sub>&#62; are usually given in &Aring;. It is also possible to give them with respect to the box dimensions with the keyword BOX and an operation (see <a href="./box.html">this page</a>).</li>
  <li><strong>screw|edge|edge_add|edge_rm|mixed</strong>: character of the dislocation. The character "mixed" can be used only when using anisotropic elasticity (see below).</li>
  <li><strong>&xi;</strong>: direction of the dislocation line, must be x, y or z.</li>
  <li><strong>n</strong>: direction normal to the plane of cut, must be x, y or z, and must be different from &xi;.</li>
  <li><strong>b</strong>: norm of the Burgers vector (in &Aring;). For dislocations of type "edge", "edge_add", "edge_rm" and "screw", only one value must be given. For the type "mixed", the three components (b<sub>1</sub>,b<sub>2</sub>,b<sub>3</sub>) must be provided.</li>
  <li><strong>&nu;</strong>: Poisson ratio of the material ; it must be provided for dislocations of character "edge", "edge_add" or "edge_rm". For dislocations of type "screw" or "mixed", it must be omitted.</li>
</ul>

<hr>
<object type="img/svg+xml" data="../img/opt_disloc_1.svg"><img src="../img/opt_disloc_1.png" alt="" /></object>
<p><strong>Fig. 1</strong> - <em>Illustration of the parameters of the option "-dislocation". &xi; is the direction of the dislocation line (x, y or z). p<sub>1</sub> and p<sub>2</sub> are the coordinates of the dislocation in the plane normal to &xi;, and <em><strong>b</strong></em> is the Burgers vector.</em></p>
<hr>


<p>By default, the dislocation is introduced using the <strong>isotropic elastic solutions</strong>.</p>

<p>For a <strong>screw dislocation</strong>, the Burgers vector <strong><em>b</em></strong> is aligned with <strong>&xi;</strong>. The total number of atoms as well as the cell vectors are unchanged. Each atom is displaced by a distance u<sub>3</sub> parallel to the dislocation line &xi;, and proportional to the norm of the Burgers vector <strong><em>b</em></strong>, according to the theory of elasticity:</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>u<sub>3</sub> = (<em>b</em>/2&pi;) atan(x<sub>2</sub>/x<sub>1</sub>)</code></p>

<p>where (x<sub>1</sub>,x<sub>2</sub>) is the position of the atom in the plane normal to the dislocation line &xi;.</p>

<p>For an <strong>edge dislocation</strong>, the Burgers vector <strong><em>b</em></strong> is normal to <strong>&xi;</strong> (so that <strong><em>b</em>.<em>&xi;</em></strong>=0), and contained inside the plane normal to &#60;n&#62;. In this case, the displacements applied to atoms are contained in the plane normal to &xi;:</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
<code>u<sub>1</sub> = (<em>b</em>/2&pi;) [ atan(x<sub>2</sub>/x<sub>1</sub>) + x<sub>1</sub>x<sub>2</sub>/(2(1-&nu;)(x<sub>1</sub><sup>2</sup>+x<sub>2</sub><sup>2</sup>)) ]</code> <br/>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>u<sub>2</sub> = (-<em>b</em>/2&pi;) [ (1-2&nu;)ln(x<sub>1</sub><sup>2</sup>+x<sub>2</sub><sup>2</sup>))/(4(1-&nu;)) + (x<sub>1</sub><sup>2</sup>-x<sub>2</sub><sup>2</sup>)/(4(1-&nu;)(x<sub>1</sub><sup>2</sup>+x<sub>2</sub><sup>2</sup>)) ]</code>
</p>

<p>where &nu; is the Poisson ratio of the material, and must be provided. With this option, an edge dislocation can be constructed in three different ways, as illustrated in <strong>Fig. 2</strong>:</p>

<ul>
  <li>With the first method, associated with the keyword <strong>edge</strong>, the edge dislocation is constructed by conserving the total number of atoms in the system (also conserving the supercell vectors). This method results in the presence of a step at one edge of the supercell, possibly messing up the boundary conditions.</li>
  
  <li>The second method, associated with the keyword <strong>edge_add</strong>, consists in duplicating the half-plane of atoms located above the dislocation, and then applying atomic displacements corresponding to the elastic field of an edge dislocation to all other atoms. Subsequently the supercell vector in the direction of the Burgers vector is elongated by half of the Burgers vector magnitude, |<strong><em>b</em></strong>|/2 -it is recommended to check it afterwards. Because this method changes the total number of atoms and the volume of the supercell, the comparison between the final and initial systems is made irrelevant. If auxiliary properties existed, then the new atoms inherit the auxiliary properties of the atoms that were duplicated.</li>
  
  <li>The third method, associated with the keyword <strong>edge_rm</strong>, consists in removing the half-plane of atoms located below the dislocation, and then applying atomic displacements corresponding to the elastic field of an edge dislocation. Subsequently the supercell vector in the direction of the Burgers vector is shortened by half of the Burgers vector magnitude, |<strong><em>b</em></strong>|/2, -it is recommended to check it afterwards. Again, beware that this method changes the total number of atoms and the volume of the supercell.</li>
  
</ul>

<p>Note that in all cases, atomic planes at the boundaries are distorted, so that boundary conditions cannot be 3-D periodic anymore.</p>

<hr>
<object type="img/svg+xml" data="../img/opt_disloc.svg"><img src="../img/opt_disloc.png" alt="" /></object>
<p><strong>Fig. 2</strong> - <em>The three possible ways to construct an edge dislocation with this option. When using the keyword "</em>edge<em>", no new atom is introduced, but the insertion of the dislocation results in the formation of a step at one border of the cell. When using "</em>edge_add<em>", a new half-plane of atoms is introduced in the system (symbolized in orange), and the box is slightly elongated. When using "</em>edge_rm<em>", a half-plane of atoms is removed from the system (in gray), and the box is slightly shrinked.</em></p>
<hr>

<p>After displacing atoms, Atomsk also computes the theoretical dislocation stresses (from the continuum theory). Since the shear modulus &mu; is unknown to this option, the stresses are normalized to it, i.e. all stresses are calculated with &mu;=1 (in other words the quantity computed is actually &sigma;/&mu;). The six Voigt components &sigma;<sub>xx</sub>, &sigma;<sub>yy</sub>, &sigma;<sub>zz</sub>, &sigma;<sub>yz</sub>, &sigma;<sub>xz</sub> and &sigma;<sub>xy</sub> are saved as auxiliary properties for each atom. If several dislocations are introduced in the system then the corresponding theoretical stresses are summed. Note that they can be written only to some files formats, like CFG (see <a href="./formats.html">this page</a> for a list of formats that support writing of auxiliary properties).</p>

<p>The use of <strong>anisotropic elasticity</strong> is automatically triggered when the elastic tensor is defined before calling the present option, e.g. through the <a href="./option_properties.html">option <code>-properties</code></a> (see specifications of this option for details on the rotation of the elastic tensor). The dislocation can have a character "screw", "edge", "edge_add", or "edge_rm", as described above. In addition, it is also possible to create a dislocation of <strong>mixed character</strong>. In this case, the three components of the Burgers vector must be given, b<sub>3</sub> being along the direction of &#60;&xi;&#62; ("screw" direction), and b<sub>2</sub> along &#60;n&#62; (normal to the glide plane). Then, the equations of anisotropic elasticity are solved to determine the coefficients <em>A<sub>k</sub>(n)</em>, <em>D(n)</em>, <em>P(n)</em> and <em>B<sub>ijk</sub>(n)</em>, and the anisotropic displacements are applied:</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>u<sub>k</sub> = </code>&real;{<code> (-2&pi;<em>i</em>)<sup>-1</sup> <strong>&sum;</strong><sub>(n=1,3)</sub> <em>A<sub>k</sub>(n) D(n)</em> ln(x<sub>1</sub>+<em>P(n)</em>x<sub>2</sub>) </code>}, k=1,3</code></p>

<p>These coefficients are also used to compute the theoretical dislocation stresses:</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>&sigma;<sub>ij</sub> = </code>&real;{<code> (-2&pi;<em>i</em>)<sup>-1</sup> <strong>&sum;</strong><sub>(n=1,3)</sub> <em>B<sub>ijk</sub>(n) A<sub>k</sub>(n) D(n)</em> / (x<sub>1</sub>+<em>P(n)</em>x<sub>2</sub>) </code>}</p>

<p>Since the elastic tensor is known, in this case it is the exact stresses that are computed. As for the isotropic case, the Voigt components are saved as auxiliary properties for each atom, and if several dislocations are constructed then their contributions to the stresses are added.</p>

<hr>

<p><strong>Dislocation loops</strong> can be constructed by using "<code>-dislocation loop</code>". In this case, the following parameters must be provided: the coordinates (x,y,z) of the center of the loop, the direction &#60;n&#62; normal to the plane of the loop (must be "X", "Y", or "Z"), the &#60;radius&#62; of the loop, the three components (b<sub>x</sub>,b<sub>y</sub>,b<sub>z</sub>) of the Burgers vector, and the value of the material's Poisson ratio &nu;. The atomic displacements follow the description of D.M. Barnett, <em>Philos. Mag. A</em> <strong>51</strong> (1985) 383-387.</p>

<p>The coordinates (x,y,z) of the center of the loop can be provided in &Aring;. It is also possible to give them with respect to the box dimensions with the keyword BOX and an operation (see <a href="./box.html">this page</a>). However, the &#60;radius&#62; of the loop and the Burgers vector components must be given in &Aring;.</p>

<p>If the &#60;radius&#62; of the loop is negative, then instead of being circular, the loop will have a square shape. The side of the square will then have a length equal to twice the absolute value of the &#60;radius&#62;.</p>

<p>For dislocation loops, the theoretical stresses are not calculated.</p>

<p>Just like the previous types of dislocations, several loops can be introduced in the system by calling the present option several times.</p>

<object type="img/svg+xml" data="../img/opt_disloc_2.svg"><img src="../img/opt_disloc_2.png" alt="" /></object>
<p><strong>Fig. 3</strong> - <em>Schematic for the construction of a dislocation loop. In this example, the dislocation loop is in a plane normal to the Cartesian Z axis (i.e. <strong><em>n</em></strong> is along Z). The dislocation loop appears in green, and its Burgers vector <strong><em>b</em></strong> in blue. Right-hand side figure: if the &#60;radius&#62; has a negative value, then the dislocation loop will have a square shape.</em></p>

<hr>

<p><strong>Important remarks:</strong> Atomsk does not "automagically" find nor adjust the Burgers vector of the dislocation, therefore a very accurate value of <strong><em>b</em></strong> must be provided. Neither does the program find the optimal position for the dislocation center: a position <code>(p<sub>1</sub>,p<sub>2</sub>)</code> that exactly matches an atom position may result in unrealistic displacements, so you may have to play around with these coordinates to obtain proper results. As always, don't trust a program blindly -check your system before running any simulation, especially when building systems with dislocation(s).</p>

<p>If a selection was defined (with the <a href="./option_select.html">option <code>-select</code></a>) then the displacements described above are applied only to selected atoms.</p>

<p>If the system contains shells (in the sense of an ionic core-shell model), then each shell is displaced by the same vector as its associated core.</p>

<p>After applying this option, some atoms may end up out of the box. If you want to wrap these atoms back into the simulation cell you may consider using the <a href="./option_wrap.html">option <code>-wrap</code></a>.</p>



<h4>Default</h4>

<p>By default no dislocation is introduced at all.</p>



<h4>Examples</h4>

<ul>
<li><code class="command">atomsk initial.cfg -dislocation 0.5*BOX 0.5*BOX screw z y 3.2 final.xyz</code>
<p>This will read <code>initial.cfg</code>, and displace atoms so as to insert a screw dislocation of Burgers vector 3.2 &Aring; lying along &xi;=Z, in a plane normal to Y. The position (p<sub>1</sub>,p<sub>2</sub>) is given in the plane normal to Z, i.e. in the (XY) plane: the dislocation is placed at the middle of the box along X (because p<sub>1</sub>=0.5*BOX) and also in the middle along Y (because p<sub>2</sub>=0.5*BOX). The result will be output to <code>final.xyz</code>.</p></li>

<li><code class="command">atomsk initial.cfg -disloc 0.25*BOX 0.5*BOX screw z y 3.2 -disloc 0.75*BOX 0.5*BOX screw z y -3.2 final.xyz</code>
<p>This will read <code>initial.cfg</code> and insert two screw dislocations of opposite Burgers vectors, the first one at (0.25;0.5) and the second one at (0.75;0.5). The result will be output to <code>final.xyz</code>.</p></li>

<li><code class="command">atomsk unitcell.xyz -duplicate 30 2 20 -disloc 30 40.2 edge_add y x 2.8 0.28 dislocation.xsf</code>
<p>This will read <code>unitcell.xyz</code>, <a href="./option_duplicate.html">duplicate it</a> to form a 30x2x20 supercell, and then construct an edge dislocation by inserting a row of new atoms. The dislocation line will lie along Y, with a Burgers vector of 2.8 &Aring;, using a Poisson ratio of 0.28, and the center of the dislocation will be placed at 30 &Aring; along Z and 40.2 &Aring; along X. The result will be output to <code>dislocation.xsf</code>.</p></li>

<li><code class="command">atomsk unitcell.xyz -duplicate 30 2 20 -disloc 30 40.2 edge y x 2.8 0.28 dislocation.cfg</code>
<p>Similar to the previous example, except that the edge dislocation will be constructued by adding a surface step  (i.e. without inserting new atoms).</p></li>

<li><div class="txtfile">
<h5>ctensor.txt</h5>
<p><code># The elastic tensor for [100] [010] [001]<br/>
elastic Voigt<br/>
243.30 243.30 243.30<br/>
145.00 145.00 145.00<br/>
116.10 116.10 116.10<br/>
<br/>
# The crystal orientation<br/>
orientation<br/>
110<br/>
1-10<br/>
001<br/></code></p>
</div>
<code class="command">atomsk initial.xyz -prop ctensor.txt -disloc 0.5*BOX 0.5*BOX screw y x 2.8 dislocation.cfg</code>
<p>Assume we want to build a dislocation in a slab of iron with crystallographic orientation X=[110], Y=[1<span class="over">1</span>0], Z=[001]. The original system (<code>initial.xyz</code>) has that orientation. In this example the <a href="./option_properties.html">option <code>-properties</code></a> is used to read the elastic tensor and the system orientation from the file <code>ctensor.txt</code>, therefore the anisotropic elasticity will be used to construct the dislocation. This is usually the most convenient way to use anisotropic elasticity for building a dislocation.</p></li>

<li><div class="txtfile">
<h5>ctensor.txt</h5>
<p><code># The elastic tensor for [100] [010] [001]<br/>
elastic Voigt<br/>
243.30 243.30 243.30<br/>
145.00 145.00 145.00<br/>
116.10 116.10 116.10<br/></code></p>
</div>
<code class="command">atomsk initial.xyz -orient 110 1-10 001 100 010 001 -prop ctensor.txt -orient 100 010 001 110 1-10 001 -disloc 0.5*BOX 0.5*BOX screw y x 2.8 dislocation.cfg</code>
<p>This example illustrates another way of doing the same thing as the previous example. The original system (<code>initial.xyz</code> which is oriented X=[110], Y=[1<span class="over">1</span>0], Z=[001]) is first rotated thanks to the <a href="./option_orient.html">option <code>-orient</code></a> so that the [100] crystal direction lies along X, [010] along Y and [001] along Z. Then the elastic tensor, which corresponds to that orientation, is read. Then the system is rotated back to its original orientation (this could also be done by using the <a href="./option_alignx.html">option <code>-alignx</code></a> instead), which also rotates the elastic tensor accordingly. Finally the dislocation can be introduced.</p></li>

<li><code class="command">atomsk supercell.cfg -dislocation loop 0.5*box 0.5*box 0.5*box Z 30 2.85 0 0 0.33 Loop.cfg</code>
<p>In this example, a dislocation loop is introduced in the middle of the box, in a plane normal to Z, with a radius of 30 &Aring; and a Burgers vector <strong><em>b</em></strong>=[2.85 0 0]. The Poisson ratio of the material is set to &nu;=0.33.</p></li>

<li><p>You may also want to look at the scripts in the "examples" folder provided with the program. The folder "<code>Al_110dislocations</code>" contains a bash script that builds two edge dislocations with opposite Burgers vectors in a slab of aluminium, using isotropic elasticity. The folder "<code>Fe_disloc_screw111_anisotropy</code>" shows how to build a 1/2&#60;111&#62; screw dislocation in iron using anisotropic elasticity.</p></li>
</ul>


<p><a href="./index.html">Back to main menu</a></p>

</body>

</html>
